❯❯ 全景導覽：守備範圍劃界與三條核心信念

📍 流水線位置｜入口 → flow → 型別 → mock → 測試 → UI → vibe → 上線（今日：全線鳥瞰）

下圖呈現了本工程流水線的整體架構，亦為後續 27 天討論的核心地圖：

文字版：

======================= 虛線以上：規格的誕生（上游領域） =======================
  [ 業務需求 ] ──> Event Storming / DDD ──> Gherkin (.feature 檔)
===========================================================================
                                     │ ( auto-generated 只讀不改 )
                                     ▼
======================= 虛線以下：我的守備範圍（流水線） =======================
  [ 雙軌入口 ] ──> [ flow 流程 ] ──> [ 型別合約 ] ──> [ Mock Server ]
                                                           │
  [ 上線/CI ]  <──  [ Vibe 治理 ]  <──  [ UI 自動生成 ]  <──  [ E2E 測試 ]
===========================================================================

在開始深入剖析各個個別架構節點之前，必須先明確劃出最頂部的這條「虛線」邊界。

位於虛線以上的環節，包含業務需求如何轉化為規格、Event Storming 討論以及 DDD 領域建模過程，在現行的實務專案中，其實是交由另一套專屬的系統機制來處理。本工程流水線的守備範圍，則專注於這條虛線以下的工程落地與自動化護欄建置。

虛線以上：規格的輸入邊界

在上游開發流程中，等視覺化工具，搭配 AI 共同梳理業務邏輯，將紛繁的需求精確拆解為事件（Events）與命令（Commands）。經過嚴謹的領域建模後，最終產出為 Gherkin 語法的 .feature 規格檔案。

這條「虛線」在我的實體專案中，其實有著非常明確且具體的標示。以婚禮專案為例，上游匯入的 .feature 規格檔，在其標頭處均統一包含著以下自動生成的關鍵註解：

# auto-generated by scripts/codegen/shared/gherkin.ts — do not edit by hand

此行註解即是明確的責任邊界。對我的工程流水線而言，這些檔案嚴格遵循「單一真理來源（SSoT）」原則，屬於不可竄改的「唯讀輸入（Read-only Input）」。一旦發現規格存在邏輯矛盾，修正的唯一路徑是回到上游調整並重新產出快照，流水線絕不直接改動原始規格檔案。

值得強調的是，良好的工程實踐並不意味著必須從零開始。只要將關鍵的工程環節進行系統化梳理並讓它穩定運轉，就能創造出極高的工程價值，這也意味著團隊即使不是 DDD 領域專家，也能直接套用這套自動化防禦機制，享有同等的品質保障。

回顧這整套技術脈絡的演進，底層其實是基於 DDD（領域驅動設計）進行領域語言建模；接著透過 BDD（行為驅動開發）將業務邏輯轉化為人機皆可讀的規格；最後再藉由 TDD（測試驅動開發）來驅動程式碼的實作。

當我們將這些方法論以「規格」作為單一源頭完整串聯起來時，這種「規格先行」的工程實踐，在業界便統稱為 Spec-Driven Development（SDD，規格驅動開發）。而我在 Day 02 所評估與討論的各類框架，本質上都是沿著這條技術路線演化而來的具體實作。

虛線以下：工程流水線的守備範圍

從接收 .feature 規格檔案開始，一路到完成 Tag 觸發自動化部署為止，全數屬於本流水線的自動化防護範疇。

為了讓後續篇章的討論具備一致的語言，我將流水線中的關鍵節點定義如下：

• 入口：支援「API 先行」與「規格先行」的雙軌接入機制。
• flow：將業務規格精確轉譯為流程邏輯，與不可破壞的「業務不變量（Invariants）。
• 型別：自動衍生前後端共用的強型別合約。
• mock：快速建構本地即時 Mock Server，解除前端對後端開發進度的依賴。
• 測試：將 E2E 自動化測試作為可執行的實體合約。
• UI：導引 AI 依據測試紅燈狀態，逐步構建頁面至全數通過（綠燈）。
• vibe：針對視覺樣式與 UI 的快速迭代，建立防止侵犯業務合約的治理機制。
• 上線：整合 Pre-push Gate、CI/CD 門禁與 Tag 自動化部署。

這些節點的核心使命，都是為了在流水線中設定嚴謹的閘門（Gate）。在 AI 高速生成程式碼的過程中，流水線必須具備即時攔截異常與邏輯偏移的能力，確保產出永遠不脫軌。

貫穿全線的三條核心信念

整套流水線基於三項工程原則建構，這些原則將於後續篇章中被持續驗證：

1. Spec 是唯一真理。
   程式碼必須完全符合規格定義，而非由程式碼反推規格。主規格一旦確立即進行凍結，僅在特定條件下解凍（Day 08 將探討將功能簡化至 API 層級的解凍實例）。

2. 測試是合約，不是保險。
   規格透過測試實體化為可執行的合約：測試描述的是系統必須遵守的行為承諾，而不是事後補救的防護網（Day 14 將說明測試合約的設計方式，Day 15 則檢驗綠燈的守備邊界）。

3. UI 可以自由，但不可以毀約。
   視覺樣式與版面配置可彈性調整，甚至交給 AI 自由揮灑，但不可違背已定義的業務邏輯（Day 18 起將以連續章節探討 UI 治理）。

Workflow 鎖定流程，工程師守住靈魂

這些工程原則規範的是開發者自身的決策行為，不該把責任全丟給 AI 模型。畢竟 AI 的運作，靠的是規格、測試案例與 CI 閘門這類可執行的具體指令；至於開發者的核心職責，則是在 AI 以極速產出程式碼、測試全亮綠燈時，依然能清醒地判定哪些業務與架構邊界絕對不可退讓。

Anthropic 在《Building Effective AI Agents》中將 AI 系統分為兩類：一種是由 LLM 自主決定執行路徑的 Agent；另一種則是將模型納入預先定義好的控制鏈中的 Workflow。我選擇 Workflow，核心考量就在於預先設定好的控制骨幹能帶來更高的穩定性與可預測性，除錯與系統診斷也輕鬆許多。

這正是我將這套系統命名為「流水線（Pipeline）」的原因。建構自動化流程的本質，從來不是為了完全放棄人工干預；恰恰相反，當自動化把開發速度推向極致時，工程師反而更需要精確掌握系統的防護邊界。

下一篇將討論實務基建：剖析這些自動化指令（如 /feature-to-flow）的實體結構，以及支撐整套工程流水線的基礎設施建置。

📎 本篇證據｜spec/gherkin-feature/ 目錄（包含 55 個規格檔案，上游匯入檔標頭均含 auto-generated 標記）